home *** CD-ROM | disk | FTP | other *** search
Text File | 1994-08-11 | 36.5 KB | 1,317 lines |
- DESQVIEW/X HELP PROGRAMMING REFERENCE
-
- The DESQview/X Help System is a general mechanism for providing on-line
- help services to applications. The basic metaphor is a wire bound
- "flip" reference with topics organized into sections. This
- widely recognized metaphor provides more information than a reference
- card in a more concise presentation than a user manual.
-
- The help notebook contains tabs along its lower edge that allow a
- user to "turn" to the beginning of a particular section, and
- navigation buttons down the right hand side. The notebook displays
- as much of a topic as possible and lists the number of pages in the
- topic as well as the topic number along its lower edge. The text of
- a topic may be accented by changes in font and color, and may contain
- pictures (or "icons"). In addition, the text may contain "hypertext"
- links whereupon if a user clicks with the mouse on a word(s), the
- notebook automatically jumps to a new topic. This "jump text"
- is usually highlighted in a different color to distinguish it from
- regular text. The buttons to the right allow a user to "backtrack"
- through a notebook (after clicking on jump text and/or section tabs),
- display the previous or next topic, display the previous or next page
- of a topic (paging up and down) as well as being able to close the
- notebook ("exit").
-
- Help System Components
-
- The DESQview/X Help System consists of the following three components:
-
- A Help File
-
- This is a single file that contains all of the notebook's
- text and pictures, instructions for moving around the notebook (jump
- instructions) as well as specifying the section tabs, colors, etc.
-
- The DESQview/X
-
- Help Engine
-
- This is the application that reads the help file, creates
- the notebook on the display screen and responds to user input.
-
- Help Interface
-
- Routines
-
- These routines are used by an application to instruct
- the Help engine to display help. They transparently handle the starting
- of the Help engine and the communication that occurs between the Help
- engine and the application. In addition, a stand alone version of
- these routines are provided in the form of the DISPHELP
- program which can be used from the command line or in a .DVP file
- to display a help notebook.
-
- This chapter first discusses how to create a Help file and is followed
- by details on using the help interface routines and the DISPHELP
- program.
-
- Creating Help Files
-
- A DESQview/X Help file begins life as a collection of files, one file
- for each topic in the notebook. In addition, there may be some additional
- files, such as .XPM files, that are used to create pictures within
- a topic as well as topic files that do not appear on their own, but
- are "included" by other topics such that they act like "subroutines".
-
- All of these files are combined into one file by using the HELPLIB
- program, included in this package. This process may be automated through
- the use of HELPLIB response files to save the tedium
- of specifying the same files to HELPLIB every time
- a help file is created.
-
- Topic files consist of ASCII text interspersed with
- special help commands (or "escape" sequences) that affect
- such things as a change in font or the defining of some jump text
- and the jump destination.
-
- Picture files are .XPM files created with a utility
- such as the DESQview/X Icon Editor.
-
- When combining files into a single help file using HELPLIB,
- the ordering of the files is of great importance. A typical help file
- consists of the following constituent files in this order:
-
- frcover
- topic1
- topic2
-
- :
-
- topicxx
- bkcover
- include1
- include2
- include3
-
- :
-
- xpm1
- xpm2
- xpm3
-
- frcover must be included and defines the cover of the notebook. It
- should be first in the help file.
-
- topic1,topic2,topic3 ... These files (which may use any
- names that you choose) are the notebook's regular displayable topics.
- When a user pages through the notebook, the topics are displayed in
- the order that their files appear in the help file.
-
- bkcover must be included and defines the section tabs that appear
- along the bottom of the notebook.
-
- In addition, bkcover defines the end of the regular displayable topics.
-
- include1,include2,include3 ... These files (which may
- use any names that you choose) appear after the bkcover
- file and are topics which are included by the regular topics (they
- act like subroutines). Since they are not stand alone topics and should
- not be displayed by themselves, they appear after bkcover.
-
- xpm1,xpm2,xpm3 ... These files (which may use any names
- that you choose) appear after the bkcover
- file and are picture files (.XPMs) which are used by both the regular
- topics and the included topics. Since they should not be displayed
- by themselves, they appear after bkcover.
-
- Topic Files
-
- Topic files (that includes frcover and bkcover) consist of
- paragraphs of text interspersed with help commands:
-
- A paragraph
-
- A paragraph of text is defined as a string of ASCII characters
- that end with a <CR> (carriage return,line feed). The <CR>
- is used to signal the end of the paragraph and will be output when
- displaying the notebook text.
-
- Help commands
-
- Help commands begin with a slash character / followed
- by a one or two letter mnemonic. If you wish the slash character to
- appear in the notebook text, a double slash // is used.
-
- An example of a topic file might be:
-
- /FH/UMoving between Application Manager Windows/U/FB<CR>
-
- <CR>
-
- To switch from one Application Manger window to another (that is make
- another window "current"):<CR>
-
- <CR>
-
- /ILmouse.xpm/Click with Button
- 1 on the border of the window you want to switch to.<CR>
-
- This topic consists of five paragraphs (three lines of text with two
- blank lines in between, each terminated by a <CR>). In addition,
- the help commands, /FH, /U, /FB, /IL are used. A full list of help
- commands is presented later.
-
- FRCOVER
-
- Frcover is a topic file that defines the text that appears on the
- cover of the notebook.
-
- An example might be:
-
- /FTApplication
- Manager<CR>
-
- /FS(c) 1990-1992 Quarterdeck
- Office Systems<CR>
-
- This directs the Help engine to:
-
- Set the font to the Cover Title font (/FT).
-
- Output "Application Manager".
-
- Output a <CR> to begin a new line.
-
- Set the font to the Cover Subtitle font (/FS).
-
- Output "(c) 1990-1992 Quarterdeck Office Systems".
-
- Output a <CR> to begin a new line.
-
- BKCOVER
-
- Bkcover is a topic file that defines the section tabs that appear
- at the bottom of the notebook. Section tabs must be defined with the
- jump command /JB. In addition,
- use of the /CT command enables you to
- define the colors of the tabs and the /IC
- command can be used to specify a picture file (.XPM) that will be
- used to create the notebook's cover.
-
- An example might be:
-
- /ICcover.xpm/<CR>
- /CTPcBrightGreen/<CR>
- /JBContents/contents/<CR>
- /CTPcYellow/<CR>
- /JBOverview/overview/<CR>
- /CTPcBrightMagenta/<CR>
- /JBCommands/details/<CR>
-
- This directs the Help engine to:
-
- Set the cover's background to cover.xpm, a picture
- file that appears in the help file after bkcover
- (/IC).
-
- Set the current tab color to PcBrightGreen, a DESQview/Xcolor
- name from RGB.TXT (/CT).
-
- Create a jump using the text "Contents" (this
- will appear on the section tab) that will go to the topic with the
- filename of 'contents' (/JB).
- This topic file is a regular displayable topic that appears between
- the frcover and bkcover
- files in the help file. The extra slashes / in this line define the
- end of the text to be output and the end of the topic filename that
- a user will jump to.
-
- Set the current tab color to PcYellow.
-
- Create a jump (i.e. tab) with the text "Overview"
- that jumps to the topic with the filename of 'overview'.
-
- Set the current tab color to PcBrightMagenta.
-
- Create a jump (i.e. tab) with the text "Details"
- that jumps to the topic with the filename of 'details'.
-
- Help Commands
-
- Help commands are split into the following categories: alignment,
- appearance, picture, utility and bkcover:
-
- Alignment
-
- Alignment commands affect the alignment of the paragraph
- they are attached to.
-
- Appearance
-
- Appearance commands change the appearance of text (fonts,
- underlining, color).
-
- Picture
-
- Picture commands display picture (.XPM) files.
-
- Utility
-
- Utility commands perform jumps (hypertext links) and
- display 'include' topics.
-
- Bkcover
-
- Bkcover commands are special commands that may only be
- used in the bkcover file.
-
- Alignment Commands
-
- Alignment commands affect the alignment of the paragraph they are
- attached to. It is very important to note that these commands affect
- the whole of a paragraph no matter where they appear in that paragraph--
- whether at the beginning or right at the end, immediately before the
- <CR>.
-
- /AL
-
- /AC
-
- /AR
-
- These commands set the general alignment of the paragraph. They perform
- the following:
-
- /AL
-
- Align paragraph to the left edge of the notebook (left
- justified).
-
- /AC
-
- Center paragraph in the middle of the notebook (centered).
-
- /AR
-
- Align text to the right edge of the notebook (right justified).
-
- Example:
-
- /ACImportant
- Note<CR>
-
- <CR>
-
- /ALNote that ...<CR>
-
- This example centers the first line and left justifies the third.
-
- /ML[+ | -]#/
-
- This command sets the left margin. If the + or - characters are not
- used, then the margin setting is absolute. If they are specified,
- this command produces a relative change.
-
- #, a decimal number that represents the number of quarter
- widths of the current font. A quarter width is the width of a typical
- character in the current font divided by 4.
-
- +, (optional) the margin setting should increase by the
- quarter widths specified.
-
- -, (optional) the margin setting should decrease by the
- quarter widths specified.
-
- Once this command has been executed, the margin setting remains in
- effect for all following paragraphs until changed again with another
- /ML command.
-
- Example:
-
- /ML+4/Indented
- Text.<CR>
-
- /ML-4/Regular Text.<CR>
-
- This example indents the text "Indented Text." by 4 quarter
- widths.
-
- /MR[+ | -]#/
-
- This command sets the right margin. If the + or - characters are not
- used, then the margin setting is absolute. If they are specified,
- this command produces a relative change.
-
- #, a decimal number that represents the number of quarter
- widths of the current font. A quarter width is the width of a typical
- character in the current font divided by 4.
-
- +, (optional) the margin setting should increase by the
- quarter widths specified.
-
- -, (optional) the margin setting should decrease by the
- quarter widths specified.
-
- Once this command has been executed, the margin setting remains in
- effect for all following paragraphs until changed again with another
- /MR command.
-
- Example:
-
- /AR/MR+4/Indented Text.<CR>
-
- /ML-4/Regular Text.<CR>
-
- This example justifies the text to the right margin and indents the
- text "Indented Text." by 4 quarter widths.
-
- /HI[+ | -]#/
-
- This command defines a hanging indent.
-
- The first line of a paragraph is never affected by this command, but
- all following lines are. This command specifies the indent of those
- lines from where the first line of the paragraph appears. If a positive
- setting is used, the lines will appear to the right of the first line.
- If a negative value is used they will appear to the left of the first
- line, but never further than the left margin of the notebook. This
- can be used to create a paragraph whereby the first line appears 'indented'
- or 'outdented'.
-
- #, a decimal number that represents the number of quarter
- widths of the current font. A quarter width is the width of a typical
- character in the current font divided by 4.
-
- +, (optional) the hanging indent setting displays subsequent
- lines indented to the right of the first line.
-
- -, (optional) the hanging indent setting displays subsequent
- lines indented to the left of the first line.
-
- Once this command has been executed, the setting remains in effect
- for all following paragraphs until changed again with another /HI or the /HC
- command.
-
- Example:
-
- /AL/ML4//HI-4/Xxxxx
- xxxxx xxxxx ..... xxxxx xxxxx xxxxx<CR>
-
- /HC/ML0/<CR>
-
- This example sets the left margin to 4 quarter widths and then sets
- the hanging indent to -4 quarter widths producing this effect:
-
- Xxxxx xxxxx xxxxx
-
- xxxxx xxxxx xxxxx xxxxx
-
- xxxxx xxxxx xxxxx xxxxx
-
- /HC
-
- This command clears any hanging indent.
-
-
-
- Appearance Commands
-
- Appearance commands change the appearance of text (fonts, underlining,
- color). They take affect wherever they appear in a paragraph.
-
- /FT
-
- /FS
-
- /FH
-
- /FL
-
- /FB
-
- /FN
-
- These commands change the font of the text to one of six fonts (that
- are chosen by the user through use of the DESQview/X Help configuration
- file, DVXHELP.CFG). Hence these commands are meta definitions and
- their definitions are as follows:
-
- /FT
-
- Cover Title font.
-
- /FS
-
- Cover Subtitle font.
-
- /FH
-
- Heading font.
-
- /FL
-
- Label font.
-
- /FB
-
- Body font (default).
-
- /FN
-
- Note font.
-
- Example:
-
- /FHA Big Heading<CR>
-
- /FLA Label/FB - and the body of the text.<CR>
-
- This produces two lines, the first in the Heading font, the second
- line beginning with the Label font, but also using the Body font.
-
- /CN
-
- /CH
-
- These commands set the color of the text to one of two colors (that
- are chosen by the user through use of the DESQview/X Help configuration
- file, DVXHELP.CFG). Hence these commands are meta definitions and
- their definitions are as follows:
-
- /CN
-
- Normal color (default).
-
- /CH
-
- Highlighted color.
-
- Note that a third color is also used for jump text (see the /JB command).
-
- Example:
-
- Something of special /CHimportance/CN to note.<CR>
-
- This example highlights the word "importance".
-
- /U
-
- This command toggles underlining on and off.
-
- Example:
-
- This /Uword/U is underlined.<CR>
-
- This example underlines the word "word".
-
- Picture Commands
-
- Picture commands display picture (.XPM) files.
-
- /ILxpmname/
-
- This command defines a picture (icon) that is displayed at the left
- margin. Any text following the picture flows to the right of the picture
- and only returns to the left edge when the following two conditions
- are met: a) the picture ends, and b) a new paragraph begins. These
- conditions produce the effect that a single paragraph next to a picture
- is indented for the entire length of the paragraph no matter which
- one ends first.
-
- xpmname is the file name of a .XPM file that appears in
- the help file after the bkcover topic.
-
- Example:
-
- /ILmouse.xpm/Click
- with Button 1 on the border of the window you want to switch to.<CR>
-
- This example produces a mouse icon to the left with descriptive text
- to the right.
-
- /IRxpmname/
-
- This command defines a picture (icon) that is displayed at the right
- margin. Any text following this command flows up to the left of the
- picture and will flow to the right edge when the picture ends.
-
- xpmname is the file name of a .XPM file that appears in
- the help file after the bkcover topic.
-
- Example:
-
- /AR/IRmouse.xpm/Click with Button 1 on the
- border of the window you want to switch to.<CR>
-
- This example produces a mouse icon to the right with descriptive text
- to the left (though, right justified).
-
- /IExpmname/
-
- This command defines a picture (icon) that is embedded within a line
- of text. This command can be used to define characters that do not
- appear within a font's character set.
-
- Note that if an embedded icon is larger than the height of the line,
- the current line height is increased to accommodate the icon.
-
- xpmname is the file name of a .XPM file that appears in
- the help file after the bkcover topic.
-
- Example:
-
- Press the Enter /IEenter.xpm/
- key.<CR>
-
- This example inserts an enter character in the middle of a sentence.
-
- Utility Commands
-
- Utility commands perform jumps (hypertext links) and display 'include'
- topics.
-
- /JBtext/topicname/
-
- This command defines both the highlighted text of a jump as well as
- its destination topic, creating a "hyperlink" in the notebook.
- This command is also used in the bkcover
- topic to define section tabs.
-
- text, the text to be displayed in the special jump text
- color.
-
- topicname, the file name of the topic to jump to. This
- topic should be a regular displayable topic whose file is listed between
- the frcover and bkcover
- files in the help file.
-
- Example:
-
- /FL/JBClick here to go to Contents/contents//FB<CR>
-
- This example outputs the text "Click here to go to Contents"
- in the Label font, highlights it with the jump color and will transfer
- the user to the 'contents' topic if selected.
-
- /Ttopicname/
-
- This command includes the referenced topic's contents at the current
- position in the current topic. This is useful in sharing common
- text/information between many topics. This command may be nested,
- such that an included topic may use this command to include another topic.
-
- Note that the current margins, paragraph alignment settings, etc.,
- are forced onto the included topic. It is advised that topics should
- be included on paragraph boundaries for predictable results. Care
- should be used to avoid excessive depth as well as circular inclusions.
-
- topicname, the file name of the topic to include. It is
- recommended that this topic should be an include topic whose file
- is listed after the bkcover file in the
- help file.
-
- Example:
-
- The error messages include:<CR>
-
- <CR>
-
- /Terrors/<CR>
-
- This example includes the topic with the file name 'errors' at the
- point specified.
-
- Bkcover Commands
-
- Bkcover commands are special commands that may only be used in the
- bkcover file.
-
- /ICxpmname/
-
- This command sets the picture (.XPM) file that should be used on the
- cover of the notebook.
-
- xpmname is the file name of a .XPM file that appears in
- the help file after the bkcover topic.
-
- Note that this command overrides the /CC command if one is specified.
-
- Example:
-
- /ICcover.xpm/
-
- This example sets the cover picture to 'cover.xpm'.
-
- /CCcolorname/
-
- This command sets the color for the cover of the notebook.
-
- colorname, this is either a valid DESQview/X colorname
- from the RGB.TXT file, or an RGB color definition, containing 1, 2,
- 3 or 4 hexadecimal values each for red,green and blue (e.g. #AAA,
- #A0A0A0, #A00A00A00, #A000A000A000).
-
- Note that this command is overridden by the /IC
- command if one is specified.
-
- Example:
-
- /CCPcGreen/
-
- This example sets the cover color to 'PcGreen'.
-
- /CTcolorname/
-
- This command sets the color for any tabs defined after the command.
-
- colorname, this is either a valid DESQview/X colorname
- from the RGB.TXT file, or an RGB color definition, containing 1. 2.
- 3 or 4 hexadecimal values each for red,green and blue (e.g. #AAA,
- #A0A0A0, #A00A00A00, #A000A000A000).
-
- This command remains in effect until changed by another definition.
-
- Example:
-
- /CTPcBrightGreen/<CR>
-
- /JBContents/contents/<CR>
-
- /CTPcYellow/<CR>
-
- /JBOverview/overview/<CR>
-
- This example defines two tabs, the first tab being PcBrightGreen and
- the second being PcYellow.
-
- Help File Structure
-
- It is recommended that help files for applications follow this structure:
-
- Contents
-
- A section containing the contents of the notebook with
- jumps into the notebook.
-
- Overview
-
- A general overview of the application and how to navigate
- within it.
-
- Commands
-
- Help for all of the commands available in the application.
-
- Dialogs
-
- Help for all of the dialogs that the application displays.
-
- Errors
-
- Help for the individual error messages the application
- issues.
-
- Naturally, you may wish to extend or customize this suggestion to
- your own particular needs.
-
- The files for this structure would probably be listed in this order
- (when presented to HELPLIB.EXE in order
- to create the help file):
-
- frcover (Front cover)
- contents (Notebook contents)
- overview (Overview contents)
- oview1 (Overview first topic)
- oview2 (Overview second topic)
-
- :
-
- commands (Commands contents)
- command1 (First command topic)
- command2 (Second command topic)
-
- :
-
- dialogs (Dialogs contents)
- dialog1 (First dialog topic)
- dialog2 (Second dialog topic)
-
- :
-
- errors (Error contents)
- error1 (First error topic)
- error2 (Second error topic)
-
- :
-
- bkcover (Back cover)
- include1 (Included topics)
- include2
-
- :
-
- xpm1 (Picture files)
- xpm2
-
- HELPLIB.EXE
-
- A utility program, HELPLIB.EXE is provided
- to create and update help files. The command line options are as follows:
-
- HELPLIB [libname | @responsefile]
-
- libname, the name of an existing library on which to perform
- maintenance.
-
- responsefile,
- the name of a file to read commands from as though they were entered
- interactively.
-
- If no response file
- is specified (i.e. no command line parameter or only a library name),
- then HELPLIB.EXE runs interactively
- with the following commands available:
-
- Add
-
- Add a file to the end
- of the help file
-
- Burst
-
- Burst a help file
- into its constituent files
-
- Change
-
- Rename the name of the help file
-
- Dir
-
- List the files added to the help file
-
- Erase
-
- Remove a file from the help file
-
- Get
-
- Copy a constituent file out of the help file
-
- Insert
-
- Insert a file into
- the help file
-
- Make
-
- Create a new help file
-
- Replace
-
- Replace a constituent
- file in the help file
-
- Use
-
- Starting using a different help file
-
- Quit
-
- Return to DOS
-
- Note that commands may be entered by first letter only.
-
- A response file contains text exactly as it would be entered interactively
- with one response per line. An example response file would be:
-
- m (Make a new file)
- newfile.hlp (name of file)
- frcover (front cover)
- contents (topic files)
- overview
- commands
- command1
- command2
- dialogs
- errors
- bkcover (back cover)
- include (include files)
- xpmfile.xpm (picture files)
- exit (exit signals end of m command)
- q (Quit)
-
- A good idea is to create a batch file that uses a response file like
- the one shown above:
-
- MAKEHELP.BAT:
-
- del newfile.hlp
-
- helplib @newfile.rsp
-
- This ensures that the topics are merged into the help file in the
- correct order.
-
- Example
-
- We shall now build an example help file. The X11 Toolkit diskettes
- contain the appropriate help example files.
-
- First, open a DOS Window and change to the correct directory:
-
- Type CD \DVX\QDECK\HELP and press Enter <CR>.
-
- Delete the old help file in case one was previously built:
-
- Type DEL EXAMPLE.HLP, press Enter <CR> and
- ignore any 'File not found' message if one appears.
-
- Create the new help file:
-
- Type HELPLIB @EXAMPLE.RSP and press
- Enter <CR>.
-
- Now copy the new help file to the help directory and display it:
-
- Type COPY EXAMPLE.HLP \DVX\HELP and press Enter
- <CR>.
-
- Type DISPHELP -F EXAMPLE.HLP and press
- Enter <CR>.
-
- It is recommended that you examine the response file EXAMPLE.RSP as
- well as the topic files it uses as an example of writing and using
- topic files.
-
- DESQview/X Help Interface
-
- When you have created your DESQview/X Help .HLP file using HELPLIB,
- your program can request that Help display a help notebook at a particular
- topic. (It should be noted that your program need not be an X client--the
- help interface routines do not rely on the X Window System.)
-
- To do this requires the use of two files - HELP.H and the DESQview/X System Library. HELP.H is a file that defines error return
- codes and prototypes for the Help interface routines--this file should
- be included into your program code. The DESQview/X System Library,
- SYSTEM.LIB, contains the Help interface
- routines and should be linked in with your program - it can be found
- in the appropriate subdirectory off the \DVX\LIB directory.
-
- HELP.H is found in the DESQview/X
- INCLUDE subdirectory, usually \DVX\INCLUDE.
-
- The four Help interface routines are:
-
- Help_initialize
-
-
- Initialize the help interface
-
- Help_get_sections
-
- Get the names of the
- notebook's sections (the names on the tabs)
-
- Help_show
-
- Display the notebook at a particular topic
-
- Help_terminate
-
- Terminate use of the help interface
-
- Typically a program will use the following sequence of calls:
-
- Help_initialize(...);
-
- :
-
- Help_get_sections(...);
-
- /* place section names on Help menu */
-
- :
-
- /* help requested! */
-
- Help_show(a_topic);
-
- :
-
- /* help requested! */
-
- Help_show(another_topic);
-
- :
-
- /* help requested! */
-
- Help_show(and_another_topic);
-
- :
-
- Help_terminate(...);
-
- Note that there is no Help_unshow (or similar command)--a user may
- close the help notebook at their discretion or leave it open. Hence
- the notebook operates independently of the application. If the user
- performs an operation in the application which generates another Help_show(...) command and
- its notebook is already open, then that notebook will appear (if iconified)
- and is updated to the specified topic.
-
- How it Works
-
- Understanding how the Help system operates is beneficial in tracking
- down problems and using the Help system effectively.
-
- The Help system consists of a Help engine running in its own DESQview
- process. This Help engine can accept requests from multiple applications
- concurrently and will create multiple independent notebooks. Even
- though applications can make requests to the Help engine directly,
- the help interface routines are provided to simplify that process.
-
- Requests are made to the Help engine using the DESQview mailbox API.
- When the Help engine has completed the operation it will return a
- status code to the sender also using the mailbox API.
-
- Let us now examine what function each of the help interface routines
- perform:
-
- Help_initialize
-
- When called, this routine sets up an "account" that contains
- information that will be sent to the Help system every time a request
- to the Help engine is made. At this point no communication with the
- Help engine (if it is present) is performed.
-
- Help_get_sections
-
- This function tries to locate the help file on disk (help files are
- relative to the Help system's directory and not the application's).
- Once the help file is located, the section names (and their corresponding
- topics) are extracted and returned to the calling application.
-
- Note that no communication with the Help engine (if it is present)
- is performed.
-
- Help_show
-
- When called, Help_show
- checks to see if the Help engine is already running. If it is not,
- Help_show starts
- the Help engine and waits for it to initialize itself. If there are
- any problems, Help_show
- will time out and return an error to the application.
-
- Once the Help engine is running (or was already running in the first
- place), Help_show
- sends a mail message request to the Help engine. The Help engine performs
- the request and sends back a status mail message to Help_show. If there
- are any problems, Help_show will time out and return an error to the
- application.
-
- Help_terminate
-
- This function sends a message to the Help engine informing it that
- the "connection" to a particular notebook is being severed
- and deallocates the account information from local storage.
-
- Help Callback
-
- There are times when the help interface routines loop is constantly
- waiting for something to happen (for example, after starting the Help
- engine and waiting for it to initialize itself, or after sending it
- a message and waiting for a reply).
-
- There can be instances when the help interface routines spend a significant
- amount of time (a few seconds) in these loops (especially when starting
- the Help engine). During this time, if a user uncovers or resizes
- one of the application's windows, the window will remain blank until
- the interface routine exits the busy-wait loop.
-
- To counteract this, the application may specify a callback routine
- that will be called whenever the help interface routines pass through
- a loop. This callback routine may perform useful work such as checking
- and reacting to Expose or ConfigureNotify events.
-
- The callback routine MUST be of the form:
-
- void helpcallback (void *user_arg);
-
- Help .DVP File
-
- The help routines specified will use the DVXHELP.DVP
- in the DESQview/X DVPs directory (normally \DVX\DVPS) to start the
- Help engine. Any changes to this .DVP may result in problems with
- the Help system.
-
- Do not have .DVPs with the same name (DVXHELP.DVP)
- located in your application directory as this .DVP file will be used
- instead and may cause problems.
-
- Help Filenames
-
- The Help engine typically runs in its own help directory (usually
- \DVX\HELP) - this is specified by the .DVP file that is used to start
- the engine (usually \DVX\DVPS\DVXHELP.DVP). Because
- of this, all requests to the Help engine must contain help file names
- that are relative to whatever directory the engine is running in.
- This is very important to remember.
-
-
-
- Help Routines
-
- A description of each of the four interface routines now follows:
-
- Help_initialize
-
- Synopsis
-
- #include <help.h>
- int Help_initialize
- (char *display_name, char *win_title, char *file_name,
- int start_timeout, int send_timeout, Help_callback callback,
- void *user_arg, HelpID *id);
-
- Description
-
- Help_initialize
- is used to initialize the help interface routines and must be called
- before any others. It returns a Help ID that is used in subsequent
- calls to save the trouble of specifying the same information (display
- name, help file name, etc.) every time. This Help id can be thought
- of as a logical "connection" to the Help system.
-
- If an application wishes to display several different notebook files
- or use several different displays, Help_initialize
- must be called separately for each instance - in each case, a different
- Help id will be returned.
-
- display_name, the display where the notebook should appear.
- If this parameter is NULL, XDisplayName is used as the display name.
-
- win_title, the window title of the notebook. If this parameter
- is NULL, "Help!" is used.
-
- file_name, the name of the help file to be used. NOTE:
- this name should be specified relative to where the Help system
- runs,normally the HELP subdirectory of DESQview/X--\DVX\HELP. If you
- store your help file in this directory (as is recommended), then no
- path is required in the filename. If you store your help file with
- your application, then pass a fully qualified drive:\path\filename
- so that the Help system may locate the file.
-
- start_timeout, the number of seconds that the help interface
- should wait after starting the Help system (using the specified .DVP)
- and the system initializing itself. If the interface times out (after
- a reasonable number of seconds - 15 or so) a problem has probably
- occurred.
-
- send_timeout, the number of seconds that the help interface
- should wait after sending a request to the Help system and waiting
- for a reply. If the interface times out (after a reasonable number
- of seconds - 10 or so) a problem has probably occurred.
-
- callback, the name of a Help callback function that is
- called whenever the help interface is waiting for a reply from the
- Help system. This callback routine can handle Expose/Configure Notify
- events, for example. If this parameter is NULL, then no callback will
- occur.
-
- user_arg, an argument that is always passed to the specified
- callback function.
-
- id, <RETURNED> the Help id created for this notebook.
-
- Help_get_sections
-
- Synopsis
-
- #include <help.h>
- int Help_get_sections(HelpID id, int *ntabs,
- char**tabs[], char**topics[]);
-
- Description
-
- Help_get_sections
- returns the number of sections and a list of section names (the tabs
- appearing along the bottom of a help notebook). These names may be
- used on a help menu, for example. In addition, the corresponding topic
- names (for use with the Help_show
- function) are also returned.
-
- id, Help id (returned by Help_initialize).
-
- ntabs, <RETURNED> the number of sections in the help file.
-
- tabs, <RETURNED> a pointer to an array of character pointers.These
- character pointers point to the section names of the help file (the
- tabs that appear along the bottom of a notebook). These section names
- were created with malloc() and may be freed with free() when no longer
- required. In addition the array of character pointers is also created
- with malloc() and may also be freed with free().
-
- topics, <RETURNED> a pointer to an array of character
- pointers.These character pointers point to each section's corresponding
- topic name in the help file. These topic names were created with malloc()
- and may be freed with free() when no longer required. In addition
- the array of character pointers is also created with malloc() and
- may also be freed with free().
-
- Help_show
-
- Synopsis
-
- #include <help.h>
- int Help_show(HelpID id, char *topic);
-
- Description
-
- Help_show instructs
- the Help system to display a notebook at a particular topic. If a
- notebook for a particular file is already open, the Help system will
- move the notebook to the foreground and update its contents to the
- new topic.
-
- id, Help id (returned by Help_initialize).
-
- topic, the name of the topic to display.
-
- Help_terminate
-
- Synopsis
-
- #include <help.h>
- int Help_terminate(HelpID id);
-
- Description
-
- Help_terminate
- is used when your application has finished with a particular notebook
- (or "connection" to the Help system).
-
- id, Help id (returned by Help_initialize).
-
- Error Codes
-
- All help interface routines can return an error code (they all return
- an integer value).
-
- These codes are:
-
- H_OK Success
-
-
-
- /* Codes returned from Help system to interface routines */
-
- PAD_NO_MEMORY No memory to complete operation
- PAD_NO_FILE Help file not found
- PAD_BAD_FILE Bad help file
- PAD_NO_TOPIC Topic not found
- PAD_BAD_CMD Bad request command - contact QOS
- PAD_SERVER_NO_MEM Server out of memory
- PAD_NO_CONNECT Couldn't connect to Server
- (XOpenDisplay failed)
- PAD_BAD_VERSION Mismatch between Help system and help
- interface version numbers
-
- /* Codes returned from all help interface routines */
-
- H_BAD_ID Help id is invalid
- H_NO_MEMORY No memory to complete operation
-
-
-
- /* Codes returned by Help_get_sections
- */
-
- H_NO_FILE Help file not found
- H_BAD_FILE Bad help file
- H_NO_TOPIC Topic not found
- H_BAD_DVPFILE Help .DVP file could not be found/read
- H_FNAME_TOO_LONG Help filename is too long
-
- /* Codes returned by Help_show
- */
-
- H_TIMEOUT Timeout occurred starting/sending message
- to Help system
-
- H_SEND_ERROR Error occurred sending message to Help
- system
-
- H_RECEIVE_ERROR Error occurred reading message from Help
- system
-
- H_START_ERROR Couldn't start Help system - .DVP
- couldn't be found, bad .DVP or
- out of memory.
-
- Example Program
-
- The X11 Toolkit contains an example program, HELPCALL, that uses the
- help interface routines. This program is contained in the \DVX\QDECK\HELP
- directory.
-
- HELPCALL illustrates how to use the help interface routines and may
- be compiled using your C compiler.
-
- Using DISPHELP
-
- Included with DESQview/X is a standalone version of the help interface
- routines--DISPHELP.EXE. This program may be used from
- the DOS command line or within a .DVP file to display a help notebook.
- (Application Manager uses this program to display all of the notebooks
- in the Help group.)
-
- DISPHELP.EXE is found in your DESQview/X directory
- (normally \DVX).
-
- Note that if an error occurs, DISPHELP displays the
- error code returned by the help interface routines--see the "Error
- Codes", section in this chapter, for a description of each error code.
-
- DISPHELP [-display displayname] [-pif
- pifname] [-spawn] [-file filename]
-
- [-topic topicname] [-name "window name"] [-help]
-
- DISPHELP accepts the following command line parameters:
-
- -display | -d displayname
-
- displayname, the display the notebook is to appear on.
- Default: your DISPLAY DOS variable, or :0 if not defined.
-
- -pif | -p pifname
-
- pifname, the .DVP file to use to start the Help system.
- Default: DVXHELP.DVP
-
- -spawn | -s
-
- This switch, when specified, instructs the Help system to spawn a
- completely separate notebook, even if an open notebook is already
- displaying the same help file.
-
- -file | -f filename
-
- filename, the help file to display. Default: DVXHELP.HLP
-
- -topic | -t topicname
-
- topicname, the topic to display. Default: contents
-
- -name | -n "window name"
-
- "window name", the name of the notebook's window.
- Default: Help!
-
- -help | -h | -?
-
- Displays a brief reminder of DISPHELP's parameters.
-